EuroCD 3

home *** CD-ROM | disk | FTP | other *** search

/ EuroCD 3 / EuroCD 3.iso / Programming / RTGMaster / devdocs / c2p.ad < prev next >

Wrap

Text File | 1998-06-24 | 24.3 KB | 654 lines

Sorry, that the docs i sent were a bit ... buggy... i now reworked the whole thing completely... but still "Beta, to be commented from people who know about what they are talking (c2p authors...)" If it changes, the final version will be somewhen available together with rtgmaster.library... The RtgMaster c2p Standard V 1.8 ================================ 1. What is it/What is rtgmaster ? 2. The Structure of a RtgMaster c2p File 3. The Functions and its specification 4. The specification of the data 5. How will this be used in an application ? 6. Error Handling 7. Includes 8. A word from the Authors 9. History --------------------------------------------------------------------------- 1. What is it/What is rtgmaster ? ================================= rtgmaster.library is a soon to be released ASM written Library for Graphicsboard AND ECS/AGA compatibility in games and demos. It is NOT a WB Emulation, but contrary to some WB Emulations it is done in a way that make that things, that demo/game coders need, EASY TO DO. Among its features, rtgmaster.library (a Beta version is available from me, MagicSN@birdland.es.bawue.de), supports a standard for c2p functions. This will used with the rtgmaster call CallRtgC2P. CallRtgC2P performs a simple "CopyPixelArray" style function for Graphics Boards (but does not use the OS, instead it directly accesses the Video Memory, using longword access where possible), and performs c2p for ECS/AGA. The c2p is choosable from a file and the c2p function will be loaded during opening the screen. This file describes how you can change your c2p algorithm so that it is usable with rtgmaster.library (you can choose the c2p using the Screenmode Requester of rtgmaster.library). I want to note, that anybody who has converted his c2p functions to the rtgmaster standard, should send them to me, so that they can be included to the rtgmaster package as soon as it is released. And, by the way... forget about that earlier "rtgmaster c2p standard" document... that was only a first try :) (Bad documentation, bad functionality, bad structure...) This here is the real thing. ---------------------------------------------------------------------------- 2. The Structure of a Rtgmaster c2p File ======================================== Primarily this is a file that will be loaded to the memory using dos.library call LoadSeg(). After being loaded in, it looks somewhat like : moveq #0,d0 rts .s dc.l "c2p!" dc.l .s dc.l 1 ; Versionnumber dc.l Structure ; Pointer to your data structure Structure is of Type c2p_Info. STRUCTURE c2p_Info,0 WORD CI_ColorDepth ;CI_256, CI_128, CI_64, CI_EHB, CI_32.. WORD CI_CPU ;CI_68060, CI_68040, CI_68030.... WORD CI_Needs ;CI_Aikiko, CI_MMU, CI_FPU... BYTE CI_Dirty ;TRUE/FALSE BYTE CI_Hack ;TRUE/FALSE ULONG CI_PixelSize ;c2p_1x1... WORD CI_WidthAlign ;Width has to be divisible by <number> WORD CI_HeightAlign ;Height has to be divisible by <number> WORD CI_Misc ;Different stuff... ULONG CI_AmiCompatible ;Is this compatible to RtgScreenAMI ? APTR CI_Description ;Pointer to a string APTR CI_Initialization ;Pointer to Initialization code APTR CI_Expunge ;Pointer to Expunge code APTR CI_Normal_c2p ;Pointer to c2p code APTR CI_Normal_c2p_InterL ;Pointer to Interleaved c2p APTR CI_Scrambled_c2p ;Pointer to Scrambled c2p APTR CI_Scrambled_c2p_InterL ;Pointer to Scrambled Interleaved c2p BYTE CI_Asynchrone ;TRUE/FALSE LABEL CI_SIZEOF In the following chapters, it will be discussed how all those entries look like, how they will be used by rtgmaster.library, how they have to be coded, what error messages have to supported and related issues. ---------------------------------------------------------------------------- 3. The functions and its specification ====================================== To support rtgmaster c2p, you will need some or more of the functions : * CI_Initialization * CI_Expunge * CI_Normal_c2p * CI_Normal_c2p_InterL * CI_Scrambled_c2p * CI_Scrambled_c2p_InterL CI_Initialization ----------------- Some c2p algorithms need an initialization part, to allocate extra Buffers, to calculate initialization conditions and similar things. This will be the place where to do this. You will get a parameter in a0, when this function is called. This parameter is a pointer to the RtgScreenAMI structure of the Screen, to which the c2p algorithm is to attach. There can only be one c2p algorithm installed in a system, but it can be changed as soon as a Screenmode-Requester of rtgmaster.library is opened (But the c2p of an already running program won't change). The CI_Initialization code will be called from the OpenRtgScreen function of rtgAMI.library, the rtgmaster sublibrary for ECS/AGA. This c2p format only supports Planar rtgmaster Sublibraries whose RtgScreen structure is compatible to RtgScreenAMI, but anyways, there do not exist Planar sublibraries for other hardware. Coders of guessed future Planar Graphics Sublibraries should be sure, that at least the entries * rsAMI_ScreenHandle * rsAMI_PlaneSize * rsAMI_Bitmap1 will be at the same place for their sublibraries, if they want to use existing c2p code. If that is not possible, they should check in their sublibrary's CallRtgC2P code for CI_AmiCompatible (more information in the chapter about the Rtgmaster c2p data structures). You might save any stuff that is allocated during the initialization part in rs_c2pdata(a0), where a0 is the before mentioned pointer to the given RtgScreenAMI structure. If your c2p code does not need any initialization, simply give 0 as the pointer to the initialization code. Parameters : a0.l = Pointer to RtgScreenAMI Output : d0.l = 0, if worked, else an errorcode (see below) CI_Expunge ---------- This function returns any system resources and memory to where they belong. It is called during CloseRtgScreen of rtgAMI.library. You will get a pointer to the RtgScreenAMI structure of the Screen, to which the c2p was attached, in a0. Parameters : a0.l = Pointer to RtgScreenAMI Output : d0.l = 0, if worked, else an errorcode CI_Normal_c2p ------------- This is the c2p main function for non-interleaved screens with contintiguous Bitmaps. As this c2p code supports rtgmaster.library, it might use up to three buffers, but that might not bother you, you will already get the correct Bitplane 0 Base addresses by CallRtgC2P. CI_Normal_c2p_InterL works much the same way, only that it is intended for interleaved Screens. It is possible to include functions for all four types of c2p functions to one c2p file. CallRtgC2P will call the correct one. Parameters : a0.l = Pointer to the Chunky Data a1.l = Pointer to Bitplane 0 a2.l = Pointer to a Byte containing the "Dirty" Flag (see below) a3.l = Pointer to the RtgScreenAMI structure, to which the c2p should be attached a4.l = Pointer to a Rectangle, like defined in include:graphics/gfx.i, which specifies, which region of the display the c2p should handle, or 0, if fullscreen c2p was intended. d0.l = c2p Modus (see below) d1.l = Planesize : (width*height)/8 d2.l = An exec signal, for asynchrone c2p Now, what should such a function do ? At first it should do error-handling, like described in a later chapter, after that it should perform c2p, and as soon as it is finished it should signal the waiting task, that it is finished. This way, you are able to implement asynchrone c2p. Even synchrone c2p algorithms have to signal the task, else it waits forever. Output : d0.l = 0, if everything worked, else error-code (see below) CI_Scrambled_c2p ---------------- This is the c2p main function for non-interleaved screens with Bitmaps, that use "scrambled" c2p. These are algorithms, where the bitplanes are not in the normally assumed order. They should still be contiguous, though. To set a standard, I have to admit, i do not know much about scrambled c2p, only that Gloom Deluxe uses it, and therefor it is specified, that rtgmaster scrambled c2p has to use the same Bitplane order as this is done for Gloom Deluxe c2p. For more information about Gloom Deluxe c2p, get GloomC2P10.lha from Aminet. It is strongly discouraged to write scrambled-only c2p, as then the coder using the c2p can't use the same chunky buffer for Graphics Boards and AGA, as CallRtgC2P does a fast "Write from Fastram-Buffer to Video-RAM" instead of c2p-ing. The user will be told, that this c2p won't work with all programs, if he chooses a scrambled chunky c2p, and he will be asked, if he wants to select the Scrambled or the Non-scrambled code, if both are available for a Rtgmaster c2p File. Scrambled c2p sometimes might be faster than non-scrambled c2p. The Parameters and output are the same as for non-scrambled c2p, and there, too, exist too types of c2p, for non-interleaved and for interleaved Bitmaps. ---------------------------------------------------------------------------------------------- 4. The specification of the data ================================ STRUCTURE c2p_Info,0 WORD CI_ColorDepth ;CI_256, CI_128, CI_64, CI_EHB, CI_32.. normally *ALL OF THEM* (see below) WORD CI_CPU ;CI_68060, CI_68040, CI_68030.... WORD CI_Needs ;CI_Aikiko, CI_MMU, CI_FPU... BYTE CI_Dirty ;TRUE/FALSE BYTE CI_Hack ;TRUE/FALSE ULONG CI_PixelSize ;c2p_1x1,... WORD CI_WidthAlign ;Width has to be divisible by <number> WORD CI_HeightAlign ;Height has to be divisible by <number> WORD CI_Misc ;Different stuff... ULONG CI_AmiCompatible ;Is this compatible to RtgScreenAMI ? APTR CI_Description ;Pointer to a string APTR CI_Initialization ;Pointer to Initialization code APTR CI_Expunge ;Pointer to Expunge code APTR CI_Normal_c2p ;Pointer to c2p code APTR CI_Normal_c2p_InterL ;Pointer to Interleaved c2p APTR CI_Scrambled_c2p ;Pointer to Scrambled c2p APTR CI_Scrambled_c2p_InterL ;Pointer to Scrambled Interleaved c2p BYTE CI_Asynchrone ;TRUE/FALSE LABEL CI_SIZEOF * CI_Colordepth : Contains the Colordepths supported by this c2p algorithm. CI_256 : AGA 256 colors CI_128 : AGA 128 colors CI_64 : AGA 64 colors CI_EHB : ECS 64 colors (EHB) CI_32 : ECS 32 colors CI_16 : ECS 16 colors CI_8 : ECS 8 colors CI_4 : ECS 4 colors CI_2 : ECS 2 colors There might be more available bits, if future Amigas support more Planar modes. Therefor i choose a WORD for this structure. If a c2p is run and a screen with the wrong colour depth is opened, the c2p operation fails. (see below) Normally you should set ALL CI_Colordepth bits (CI_256+CI_128+CI_64+CI_EHB+CI_32+CI_16+CI_8+CI_4+CI_2), as rtgmaster.library supports ALL Depths automatically, if you do not use special features of the AGA Chipset, that are not available on ECS (for example long blits...). If your c2p only runs on 8 Bit, that's not a problem... rtgmaster.library provides some dummy bitplanes for you, then... * CI_CPU : Contains information about the supported CPU. CI_68060 : Runs on 68060. CI_68040 : Runs on 68040. CI_68030 : Runs on 68030. CI_68020 : Runs on 68020. These bits are set, if it runs, cleared, if not. As rtgmaster.library needs 68020 at least, no Bits for 68000/68010. CI_68060D : Don't know, if it runs on 68060. CI_68040D : Don't know, if it runs on 68040. CI_68030D : Don't know, if it runs on 68030. CI_68020D : Don't know, if it runs on 68020. This might be expanded in the future, as soon as Power PC Amigas with 680x0 emulations will appear. * CI_Needs : Some c2p needs special hardware to run. CI_68060N : 68060 only code. CI_68040N : Needs 68040 at least. CI_68030N : Needs 68030 at least. CI_Aikiko : Needs Aikiko. CI_MMU : Needs an MMU. CI_FPU : Needs an FPU. CI_FAST : Needs Fastram. CI_2MB : Needs 1 MB Chip. This might be expanded in the future. Notice, that the hardware won't be checked for the correct cpu, but the information will be given to the user. Maybe it will be checked when the user selects the c2p for his system in a future version of rtgmaster.library. (see below) * CI_PixelSize : Which Pixelsizes are supported by the c2p. c2p_1x1 c2p_1x2 c2p_2x1 c2p_2x2 c2p_2x4 c2p_4x2 c2p_4x4 are the types for which the "Dirty" Flag will be ignored. The Dirty Flag specifies (if set), that not all CI_WidthAlign Pixels have to be processed, if not needed. c2p_1x1D c2p_1x2D c2p_2x1D c2p_2x2D c2p_2x4D c2p_4x2D c2p_4x4D are the types that try to use the "Dirty" Flag. It could still be set to 0, though. c2p_Best and c2p_BestD try to use the highest resolution mode. c2p_Fastest and c2p_FastestD try to use the fastest ones. c2p_Selected and c2p_SelectedD try to use the one selected by the user as standard c2p. You won't have to specify the Best, Fastest and Selected Flags, as they will be supported for ALL c2p algorithms. You will have to check yourselves, if the ordered mode is existing in this c2p (see below). * CI_Dirty : Specifies if this c2p supports a dirty flag. It can be true (1) or false (0). * CI_Hack : Specifies, if this c2p uses some ugly hardware hacks, that might not run on Intuition Screens. It then only will be used with a still not existing hardware-banging RtgScreenAMI compatible rtgmaster sublibrary. Only specify this, if it REALLY does not run with Intuition Screens. Planar sublibraries that are for hardware other than ECS/AGA, will fail, if trying to use such c2p code. Can be true (1) or false (0). * CI_Asynchrone : Specifies, if the c2p code is asynchrone (1) or synchrone (0). * CI_WidthAlign : Specifies, if the c2p code needs a screen whose width is divisible by a certain number. This value contains this number, or 0, if this is not needed. * CI_HeightAlign : The same for the height. * CI_Misc : CI_Smaller : If this bit is set, the c2p algorithm supports c2p-ing rectangles that are smaller than Full-Screen. CI_Fixed : If this is set, the c2p algorithm ONLY works together with Screens of the resolution specified in CI_WidthAlign/CI_HeightAlign. NOTE : FIXED c2p algorithms are NOT ALLOWED to need a Width/Height Align !!! (Makes no sense, anyways, if they are fixed :) ) CI_Destruct : c2p is destructive c2p. Most c2p are non-destructive (they do not change the chunky buffer in displaying it) CI_Misc might be expanded in the future. * CI_AmiCompatible : Contains 'AMI ', if this c2p code is compatible with RtgScreenAMI. If not, it contains the code of the sublibrary with that it is compatible (three letters + blank or four letters). * CI_Description : Points to a string discribing this c2p algorithm. Up to 255 letters, 0-terminated. ---------------------------------------------------------------------------------------------- 5. How will this be used in an application ? ============================================ Normally this c2p will be called using rtgmaster.library function CallRtgC2P. I am including the Autodocs for CallRtgC2P at the end of this chapter. People who are interested in rtgmaster.library, should mail me at MagicSN@birdland.es.bawue.de The c2p code is integrated the following way : 1. The user selects a c2p code to be used for his systemusing the rtgmaster Screenmode Requester. The Path of this file will be stored in envarc:rtgmaster/c2p. Then he chooses a default mode, that will be stored in envarc:rtgmaster/c2pcurr. 2. As soon as an application opens a RtgScreen, the c2p algorithm is loaded to memory, using LoadSeg() of dos.library, and the default c2p is stored in the RtgScreen structure. After that, a possibly existing initilaization function of the c2p will be called and the data it returns will be saved in the RtgScreen structure. Some error checks will be done (see below) 3. As you call CallRtgC2P, the c2p will be performed, with some error checks (see below). If it returns 0, everything worked, else an error happened. Some of the error checks will be done in CallRtgC2P, some will have to be done in your c2p code (see below). 4. The application waits with exec.library Wait() for the c2p to be finished, even if it is synchrone c2p. The application should not leave out this Wait(). 5. If CloseRtgScreen is called, the Expunge function will be called (if it exists), and after that, UnloadSeg() of dos.library will be called. DO NOT PROVIDE BOTH scrambled and not-scrambled functions... split the thing to two c2p files... rtgmaster.library can't handle this, else... it is possible to provide interleaved and not interleaved stuff in one file, though... Certainly, Rtgmaster c2p is usable without having to use rtgmaster.library, too, but this is recommended. Both rtgmaster.library and the rtgmaster c2p format are freeware. Up to what c2p functions are, copyright is up to those who wrote the functions. But most of them should probably be freeware, too. ---------------------------------------------------------------------------------------------- 6. Error Handling ================= The Rtgmaster c2p format knows the following error messages. They will be returned by CallRtgC2P. I. c2p_err_Wrong_C2P II. c2p_err_Wrong_Depth III. c2p_warn_Wrong_Pixelmode IV. c2p_err_Wrong_Windowsize V. c2p_warn_divisible VI. c2p_err_hardware VII. c2p_err_memory VIII. c2p_err_internal IX. c2p_warn_internal I. will come up, if you, for example, try to do an interleaved-only c2p with a interleaved Bitmap. This will be checked by CallRtgC2P itself. II. will come up, if the Display has a depth, that is not supported by the c2p code. This will be checked by CallRtgC2P itself. III. will come up, if you tried to use a Pixelmode, that is not available for this c2p. It is only a warn, and your c2p code should use a mode, that finds to be a appropriate replacement. It will still do c2p, but it should return this warning. The c2p code should check for this, as it knows its possibilities and features best. IV. will come up, if you tried to do a "smaller than Fullscreen" c2p with a c2p that only can do Fullscreen c2p. This will be checked by CallRtgC2P itself. This will be done first, so a 1. Try to do "smaller than Fullscreen" 2. Did not work => Recalculate and do Fullscreen c2p should be optimal. V. will come up, if you tried to use illegal widths/heights for this c2p. You might configure the Rtgmaster Screenmode Requester c2p choosing utility to filter out such modes, though, so this warn will only appear, if you do not filter out. It will then try to do the c2p, anyways and wish you good luck :) VI. will be given from CallRtgC2P, if you tried to do a c2p that is not compatible with the given Display hardware. Processor hardware won't be checked, but this might be implemented in the Rtgmaster Screenmode Requester c2p choosing utility later. VII. is the error that you should return, if your initialization/expunge code fails, due to the system being low on memory. VIII./IX. is the error you should return, if something happens that is nothing of the other stuff. It exists as warn and as error. --------------------------------------------------------------------------------------------- 7. Includes =========== You probably should get : - Standard AmigaDOS Includes for OS2.0 or higher - rtgmaster.library includes (available from me, MagicSN@birdland.es.bawue.de) I am listing the RtgScreenAMI structure out of rtgAMI.i here for better understanding (note : in the docs of rtgmaster.library it is stated, that this structure would be private to rtgmaster.library. It is private to rtgmaster.library *and* rtgmaster c2p now...) STRUCTURE RtgScreenAMI,0 STRUCT rsAMI_Header,rs_SIZEOF UWORD rsAMI_Locks ALIGNLONG ULONG rsAMI_ScreenHandle ULONG rsAMI_PlaneSize ULONG rsAMI_DispBuf ;Buffer currently displayed ULONG rsAMI_ChipMem1 ULONG rsAMI_ChipMem2 ULONG rsAMI_ChipMem3 STRUCT rsAMI_Bitmap1,40 STRUCT rsAMI_Bitmap2,40 STRUCT rsAMI_Bitmap3,40 ULONG rsAMI_Flags STRUCT rsAMI_MyRect,8 STRUCT rsAMI_Place,36 LABEL rsAMI_SIZEOF Now i am listing include:rtgmaster/rtgc2p.i : STRUCTURE c2p_Info,0 WORD CI_ColorDepth ;CI_256, CI_128, CI_64, CI_EHB, CI_32.. WORD CI_CPU ;CI_68060, CI_68040, CI_68030.... WORD CI_Needs ;CI_Aikiko, CI_MMU, CI_FPU... BYTE CI_Dirty ;TRUE/FALSE BYTE CI_Hack ;TRUE/FALSE ULONG CI_PixelSize ;c2p_1x1,... WORD CI_WidthAlign ;Width has to be divisible by <number> WORD CI_HeightAlign ;Height has to be divisible by <number> WORD CI_Misc ;Different stuff... ULONG CI_AmiCompatible ;Is this compatible to RtgScreenAMI ? APTR CI_Description ;Pointer to a string APTR CI_Initialization ;Pointer to Initialization code APTR CI_Expunge ;Pointer to Expunge code APTR CI_Normal_c2p ;Pointer to c2p code APTR CI_Normal_c2p_InterL ;Pointer to Interleaved c2p APTR CI_Scrambled_c2p ;Pointer to Scrambled c2p APTR CI_Scrambled_c2p_InterL ;Pointer to Scrambled Interleaved c2p BYTE CI_Asynchrone ;TRUE/FALSE LABEL CI_SIZEOF ; CI_ColorDepth CI_256 EQU 256 CI_128 EQU 128 CI_64 EQU 64 CI_EHB EQU 32 CI_32 EQU 16 CI_16 EQU 8 CI_8 EQU 4 CI_4 EQU 2 CI_2 EQU 1 ; CI_CPU CI_68060 EQU 1 CI_68040 EQU 2 CI_68030 EQU 4 CI_68020 EQU 8 CI_68060D EQU 16 CI_68040D EQU 32 CI_68030D EQU 64 CI_68020D EQU 128 ; CI_Needs CI_68060N EQU 1 CI_68040N EQU 2 CI_68030N EQU 4 CI_Aikiko EQU 8 CI_MMU EQU 16 CI_FPU EQU 32 CI_FAST EQU 64 CI_2MB EQU 128 ; CI_Misc CI_Smaller EQU 1 CI_Fixed EQU 2 CI_Destruct EQU 4 ; CI_PixelSize c2p_1x1 EQU 1 c2p_1x2 EQU 2 c2p_2x1 EQU 4 c2p_2x2 EQU 8 c2p_4x2 EQU 16 c2p_2x4 EQU 32 c2p_4x4 EQU 64 c2p_Best EQU 128 c2p_Fastest EQU 256 c2p_Selected EQU 512 c2p_1x1D EQU 1024 c2p_1x2D EQU 2048 c2p_2x1D EQU 4096 c2p_2x2D EQU 8192 c2p_4x2D EQU 16384 c2p_2x4D EQU 32768 c2p_4x4D EQU 65536 c2p_BestD EQU 131072 c2p_FastestD EQU 262144 c2p_SelectedD EQU 524288 ---------------------------------------------------------------------------------------------- 8. A word from the Authors ========================== This rtgmaster c2p format was mainly done by me, Steffen Haeuser, with the help of Ludvig Pedersen and Peter McGavin. rtgmaster.library was/is done by me, John Hendrikx, Wolfram Schenk and Hans-Joerg Frieden. CallRtgC2P is supported by rtgmaster sublibraries starting with version number 2.0. Up to now no c2p functions are finished, so send me some :) Note for people who want some very special c2p : - Fixed for certain resolutions : let it fail for all other resolutions with #c2p_err_internal and write a note to CI_Description. - Scrambled c2p *and* Normal c2p : You have to make two files out of it. This standard can't handle both of them in one file. - Vertical doubled pixels : Write a sublibrary that bases on hardware banging displays and uses vertical doubled pixels, using "Pseudo Screenmodes". Sorry, up to now, no other solutions. Maybe later... :) ---------------------------------------------------------------------------------------------- 9. History ========== 1.0 First version to be worth mentioned 1.1 Structures were rearranged a LOT... 1.2 Updated RtgScreenAMI and added some hints to 8. 1.3 Updated RtgScreenAMI + changed c2p_* values 1.4 Updated c2p_Info structure (replaced BOOL by BYTE) 1.5 Updated RtgScreenAMI + Bugfix in description of Initialization (stuff has to be saved in c2pdata, NOT in c2pcode... Errorcodes in Initialization/Expunge fixed) 1.6 Added CI_Fixed for Fixed Screenmode c2p. 1.7 Added CI_Destruct 1.8 Added ECS compatibility note at the CI_Colordepth section (normally rtgmaster.library has automatic ECS Support... as long as no special AGA features asides from colordepth are used for the c2p, that is...)